﻿/*--------------------------------------------------------------------------------
 * Adaptive Intelligence - Foundation Framework
 * Version 2.10
 * 
 * CNR Command Base Class
 *      Provides an abstract base definition for implementing commands in
 * a command-and-response protocol.
 *------------------------------------------------------------------------------*/

/*--------------------------------------------------------------------------------
 * System Imports
 *------------------------------------------------------------------------------*/
using System;
using Adaptive.Foundation;

namespace Adaptive.Foundation.Network.Cnr
{
    /// <summary>
    /// Provides an abstract base definition for implementing commands in 
    /// a command-and-response protocol.
    /// </summary>
    /// <remarks>
    /// This base class is intended to be extended for the specific application within a 
    /// particular command-and-response protocol, such as FTP, E/SMTP, POP3, and others.
    /// 
    /// The specifics of each command implementation, and the related derivatives of the 
    /// <see cref="CnrResponseBase"/> implementations are left to the implementors
    /// of each protocol.
    /// </remarks>
    public abstract class CnrCommandBase : CnrObjectBase
    {
        /*--------------------------------------------------------------------------------
         * Public Event Definitions
         *------------------------------------------------------------------------------*/
        #region Public Event Definitions
        /// <summary>
        /// Occurs when the command begins to be executed.
        /// </summary>
        public event EventHandler StartExecute;
        /// <summary>
        /// Occurs when command execution completes.
        /// </summary>
        public event EventHandler CompleteExecute;
        #endregion

        /*--------------------------------------------------------------------------------
         * Private Member Declarations
         *------------------------------------------------------------------------------*/
        #region Private Member Declarations

        private int _commandTypeValue;
        private CnrCommandParameterCollection _parameters;

        #endregion

        /*--------------------------------------------------------------------------------
         * Constructor / Dispose / Destructor Methods
         *------------------------------------------------------------------------------*/
        #region Constructor / Dispose / Destructor Methods
        /// <summary>
        /// Initializes a new instance of the class.
        /// </summary>
        /// <param name="commandName">
        /// The name of the command,
        /// </param>
        public CnrCommandBase(string commandName)
            : base()
        {
            Name = commandName;
            _parameters = new CnrCommandParameterCollection();

        }
        /// <summary>
        /// Initializes a new instance of the class.
        /// </summary>
        /// <param name="commandName">
        /// The name of the command,
        /// </param>
        /// <param name="commandValue">
        /// A numeric value that identifies the command.
        /// </param>
        public CnrCommandBase(string commandName, int commandValue)
            : base()
        {
            Name = commandName;
            _parameters = new CnrCommandParameterCollection();
            _commandTypeValue = commandValue;

        }
        /// <summary>
        /// Deallocates internally allocated objects.
        /// </summary>
        /// <param name="disposing">
        /// A value indicating whether the object is being disposed.
        /// </param>
        protected override void Dispose(bool disposing)
        {
            if ((!Disposed) && (disposing))
            {
                if (_parameters != null)
                    _parameters.Dispose();
            }

            _parameters = null;
            base.Dispose(disposing);
        }
        #endregion

        /*--------------------------------------------------------------------------------
         * Public Properties
         *------------------------------------------------------------------------------*/
        #region Public Properties
        /// <summary>
        /// Gets the reference to the list of parameters used in the command.
        /// </summary>
        /// <value>
        /// A <see cref="CnrCommandParameterCollection"/> instance.
        /// </value>
        public CnrCommandParameterCollection Parameters
        {
            get { return _parameters; }
        }
        /// <summary>
        /// Gets or sets a numeric value used to identify the command.
        /// </summary>
        /// <value>
        /// An integer value to associate with the command instance.
        /// </value>
        public int CommandValue
        {
            get { return _commandTypeValue; }
            set { _commandTypeValue = value; }
        }
        #endregion

        /*--------------------------------------------------------------------------------
         * Protected Methods / Event Methods
         *------------------------------------------------------------------------------*/
        #region Protected Methods / Event Methods
        /// <summary>
        /// Executes the command.
        /// </summary>
        /// <returns>
        /// A <see cref="CnrResponseBase"/> instance containing the result of the execution.
        /// </returns>
        public abstract CnrResponseBase Execute();
        /// <summary>
        /// Executes the command using the specified object.
        /// </summary>
        /// <param name="executionContextItem">
        /// An object containing data and/or used to execute the command.
        /// </param>
        /// <returns>
        /// A <see cref="CnrResponseBase"/> instance containing the result of the execution.
        /// </returns>
        public abstract CnrResponseBase Execute(object executionContextItem);
        /// <summary>
        /// Renders the command as a string.
        /// </summary>
        /// <returns>
        /// A string containing the command and parameter values.
        /// </returns>
        protected abstract string RenderCommand();
        /// <summary>
        /// Renders the command as a string.
        /// </summary>
        /// <returns>
        /// A string containing the command and parameter values.
        /// </returns>
        /// <param name="renderer">
        /// A <see cref="CnrDataRendererBase"/> instance used to render the command.
        /// </param>
        protected abstract string RenderCommand(CnrDataRendererBase renderer);
        /// <summary>
        /// Parses the original data content into the command object.
        /// </summary>
        /// <param name="parser">
        /// A <see cref="CnrDataParserBase"/> instance used to parse the command text.
        /// </param>
        /// <param name="originalData">
        /// The original data to be parsed.
        /// </param>
        protected abstract void ParseCommand(CnrDataParserBase parser, string originalData);
        /// <summary>
        /// Raises the <see cref="StartExecute"/> event.
        /// </summary>
        /// <param name="e">
        /// A <see cref="EventArgs"/> event arguments instance.
        /// </param>
        protected virtual void OnStartExecute(EventArgs e)
        {
            if (StartExecute != null)
                StartExecute(this, e);
        }
        /// <summary>
        /// Raises the <see cref="CompleteExecute"/> event.
        /// </summary>
        /// <param name="e">
        /// A <see cref="EventArgs"/> event arguments instance.
        /// </param>
        protected virtual void OnCompleteExecute(EventArgs e)
        {
            if (CompleteExecute != null)
                CompleteExecute(this, e);
        }
        #endregion

        /*--------------------------------------------------------------------------------
         * Public Methods / Functions
         *------------------------------------------------------------------------------*/
        #region Public Methods / Functions
        /// <summary>
        /// Clears the contents of the object instance without disposing of the instance.
        /// </summary>
        public override void Clear()
        {
            _commandTypeValue = 0;
            if (_parameters != null)
                _parameters.Clear();
            Name = string.Empty;
        }
        #endregion
    }
}